## B.2. perldoc

Developers new to Perl often overlook a very valuable source of information: `perldoc`. `perldoc` is Perl's documentation viewer; it allows you to read documentation in Perl's pod (plain old documentation) format. This provides a wealth of information about Perl, plus modules. Virtually every module included with Perl and available on CPAN includes pod.

If `perl` works on your system but the `perldoc` command does not, you may need to search your system for it. It is installed with Perl by default, but depending on the installation, it may not have been installed in a standard executable directory. You can also fall back to using `man` instead. pod pages are typically converted to manpages when they are installed.

To get started, try the following command:

>     $ perldoc perl

This provides a basic description of Perl along with a list of the Perl manual sections available. For instance, typing:

>     $ perldoc perlsec

will display the Perl security section. `perldoc` has a number of options; you can get the usage of perldoc this way:

>     $ perldoc perldoc

perldoc is very useful with modules. You can view the extensive documentation for CGI.pm this way:

>     $ perldoc CGI

This sequence works for multiple-word modules:

>     $ perldoc Digest::MD5

Note that the requested module must be present; `perldoc` does not fetch documentation from CPAN. In addition to package names, you can also supply a filename to `perldoc`; this allows you to view the documentation for a module before it is installed:

>     $perldoc ./MD5.pm

pod is typically stored within .pm files, although separate .pod files are possible.

Finally, if you prefer a graphical interface, you may wish to look at the Tk::Pod module.

Copyright © 2001 O'Reilly & Associates. All rights reserved.